<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Control Messages
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot056.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot058.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc113">10.5</A>&nbsp;&nbsp;Control Messages</H2><UL>
<LI><A HREF="embroot057.html#toc61">The disconnection protocol</A>
</UL>

These are the messages that are exchanged between the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and remote
sides when the remote side is attached. The messages are sent on the
control connection, and are in EXDR format. All arguments for the messages
are either atoms or integers. The messages are used to
co-ordinate and synchronise the two sides. A message should only be sent from a
particular side when that side has control, and control is handed over
to the other side when the message is sent. <BR>
<BR>
Most messages are used to initiate an <I>interaction</I> with the
other side. That is, used to cause some action to take place on the
other side: control is handed over, the action takes place on the other
side, and eventually control is handed back 
when the action is completed. Control can also be explicitly handed over
from one side to the other so that the other side can initiate
interactions. Some additional messages can only be sent as part of an
interaction, for exchanges of information between the two sides. Finally,
there are messages for terminating the remote attachment. Note that
interactions can be nested, that is, an interaction from one side can
contain an interaction initiated from the other side. <BR>
<BR>
The implementer for the remote interface should provide the methods for a
programmer to initiate the interactions from the remote side. These
routines would send the appropriate control messages to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side, and the messages should not be directly visible to the programmer. <BR>
<BR>
The usage of each message is summarised in the diagram(s) accompanying
them. These diagrams show:
<UL CLASS="itemize"><LI CLASS="li-itemize">
time proceeds downward. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side is shown on the left,
the remote side on the right. Messages are shown as vertical arrows between
the two sides. The direction of the arrow indicates the direction the
message is sent.<BR>
<BR>
<LI CLASS="li-itemize">the context in which the message can be sent, i.e. the message from
the other side that it is either expecting as a response, or that it is a
response to. The message sequence is shown, with the message highlighted.<BR>
<BR>
<LI CLASS="li-itemize">any accompanying actions expected with the message. These actions are
either sending or receiving data on some other connections between the two
sides. These are shown as dashed arrows in the diagrams.<BR>
<BR>
<LI CLASS="li-itemize">whether nested interactions can take place between messages of an interaction.
This is indicated by vertical ellipsis between the messages in
the diagram. In such cases, the nested interaction can be initiated, and this
interaction completed before the next message for the original interaction
is expected.
</UL>

<H5 CLASS="paragraph">From ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side to the remote side</H5>
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>yield</B><DD CLASS="dd-description"> this yields control to the remote side. The message is used either to
implicitly return control to the remote side at the end of an 
interaction initiated from the remote side, or it
is used to explicitly hand over control to the remote side. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot007.gif"></DIV><BR>
<BR>
The interaction-initiating messages from the remote side will be described
in more detail in their own sections.<BR>
<BR>
<DT CLASS="dt-description"><B>ec_flushio(Queue, Length)</B><DD CLASS="dd-description"> this message is sent when output on a remote
synchronous queue is flushed on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side:<BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot008.gif"></DIV><BR>
<BR>
Queue is the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> stream number for the peer queue, and Length is the number of bytes
that is being sent on the queue. Control is yielded to the remote
side. The data on the queue Queue will be sent through the
queue after sending this message on the control connection, so on receiving
this message on the remote side, the remote side should read Length bytes from
Queue. After processing the data, the remote side should return
control to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side via a <B>resume</B> message.<BR>
<BR>
<DT CLASS="dt-description"><B>ec_waitio(Queue)</B><DD CLASS="dd-description"> this message is sent when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> requests input
from a remote synchronous queue, and the data is not available in the
queue's buffer. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot009.gif"></DIV><BR>
<BR>
This interaction is triggered when the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side attempts a read
operation on the empty buffer of a peer queue. The operation is suspended, 
and control is yielded to remote side so that it can provide
the required data. There should be a data-provider handler associated with
the queue on the remote side. This handler should obtain the data, and send
the data to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. The data will arrive from the remote side via a
<B>rem_flushio</B> message, which initiates a remote flushio interaction, nested
within the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> waitio interaction. The data arrives on the socket
associated with the remote peer queue Queue, and is automatically copied by
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> into the peer queue buffer. Control is then yielded back to 
the remote side, completing the flushio interaction. The remote side then
hands control back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side by the resume message. The suspended
read operation is resumed on the now non-empty buffer. <BR>
<BR>
The remote flushio interaction is described in more detail in its own
section. The main difference between a remote flushio initiated on the
remote side and one initiated by an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> waitio described here is
that there must not be a data-consumer handler on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, as
the data is to be consumed by the suspended read operation instead.
This is ensured in the protocol by prohibiting handlers on both sides 
of a synchronous peer queue.<BR>
<BR>
Note that the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will also listen to the control connection
while waiting for the data to be sent from the remote side. If a <B>resume</B> is sent before the data arrives, this is likely caused by a
programming error in the data provider handler, which finished without
sending data to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will print a
warning message on the warning output stream, and immediately yield
back to the remote side. Other messages are handled as normal, recursively
while waiting for the data to arrive &ndash; this is mainly intended to allow
for unexpected aborts from the remote side, although it could also be used to
perform ec_rpc calls before the remote side sends the data.<BR>
<BR>
<DT CLASS="dt-description"><B>socket_client(Port, Name, Type, Dir)</B><DD CLASS="dd-description"> this requests the remote side
to form a client socket connection for the remote peer queue Name. The
queue is of type Type (sync or async), and direction Dir (fromec, toec for
synchronous queues, bidirect for asynchronous queues). The client socket is
to connect at port Port with the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side host name. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot010.gif"></DIV><BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side first creates a server socket for the peer queue Name.
The port address is Port. This, along with the details of the queue is
passed to the remote side via the <B>socket_client</B> message. The remote side
should then connect a client socket with Port as the port, and the Host
used for the initial attachment (which is either localhost or the hostname
of the <CODE>eclipse</CODE> side) for the host. 
It should also perform any additional
setups for the peer queue using the information sent with the message
(typically this involve setting up book-keeping information for the queue
on the remote side). When the remote side connection is established, it
returns control to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> via a <B>socket_connect</B> message:<BR>
<BR>
<B>socket_connect(Name, Status)</B><BR>
<BR>
Name is the name of the queue, and should be the same as the Name sent by
the socket_client message. This is used to verify that the messages refer
to same interaction. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will raise an error and disconnect
from the remote side if the name does not match. Status is either 
success or fail, depending on if the remote side successfully created the
remote side of the queue or not.<BR>
<BR>
If Status is success, then the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will complete the connection
for the peer queue by accepting the socket connection. Since the remote end
of the socket exists, the accept operation should succeed very
quickly. If not, the operation will time-out, using the time-out interval
specified when the attachment was made. The server socket is closed
immediately after the accept operation. On successful connection,
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> first checks that this client's host is indeed the same as the
one previously recorded for the remote side. If so, the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will finish creating the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side of the queue. If not,
the connection is closed, and the operation is considered to have failed. <BR>
<BR>
If Status from the socket_connect message is fail,
then the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will clean up the preparation for the peer queue. <BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side then returns control to the remote side via a
<B>socket_accept</B> message:<BR>
<BR>
<B>socket_accept(Name,Queue)</B><BR>
<BR>
Name is again the name of the queue, and Queue the stream id. If the accept
was unsuccessful (or if Status for socket_connect was fail), then Queue
will be the atom fail, indicating that the peer queue connection was
unsuccessful. <BR>
<BR>
The remote side should then record the id Queue for later use (it is
needed for the control messages connected with this peer queue). If instead
fail was received, then the remote side should clean up the attempted queue
connection. When the remote side has finished the final stage of the
connection, control is returned to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side via a <B>resume</B>
message, and the socket_client interaction completes.<BR>
<BR>
Note that the <B>socket_connect</B> and <B>socket_accept</B> messages are
always exchanged during a socket_client interaction, even if the connection
failed on the remote side before <B>socket_connect</B> is sent. They also
can only occur in this context. If these messages occur in any other
occasion, an error should be raised.<BR>
<BR>
<DT CLASS="dt-description"><B>queue_close(Queue)</B><DD CLASS="dd-description"> this message is sent when the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side
closes the peer queue with id Queue. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot011.gif"></DIV><BR>
<BR>
The remote side should close the remote side of the peer queue Queue, and
remove all bookkeeping information associated with it. Control should then
be returned to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> via a <B>resume</B> message. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side should
also close the queue and remove bookkeeping information on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side.<BR>
<BR>
<DT CLASS="dt-description"><B>disconnect</B><DD CLASS="dd-description"> this message is sent when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side initiates
disconnect. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot012.gif"></DIV><BR>
<BR>
Control is yielded to the remote side, which should acknowledge
with the <B>disconnect_resume</B> message. Once the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side receives this
message, the connection between the two sides is considered
terminated. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will then close all the connections (the
control and ec_rpc connections, and any asynchronous and synchronous
queues) to the remote side, and clean up the information associated with the
attachment. After sending the disconnect_resume message, the remote side
should also shutdown its end of the connection by closing all the
connections on its side. <BR>
<BR>
Note that the disconnection message can be used to terminate the attachment
from within an interaction. In such cases, the interaction(s) would not be
completed.<BR>
<BR>
<DT CLASS="dt-description"><B>disconnect_yield</B><DD CLASS="dd-description"> this message is sent when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side receives
a <B>disconnect</B> message from the remote side, i.e. the remote side
initiated disconnection. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot013.gif"></DIV><BR>
<BR>
This message is sent as an acknowledgement to the
disconnect message. Once the disconnect_yield is sent, the connection is
considered terminated, and the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will close all the
connections and clean up. After the clean up, abort is called. This is
done because the application on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side (such as the remote
development tools) may be deep inside some interaction loop with the remote
side, and abort is the most general way of escaping from such a loop. It
can be caught (see <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default332"></A> in section&nbsp;<A HREF="embroot058.html#remotesupport">10.6</A>) if
the user wants a more graceful termination. </DL>

<H5 CLASS="paragraph">Messages from remote side to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side</H5>
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><B>resume</B><DD CLASS="dd-description"> this message hands over control from remote side to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. This is used to either implicitly return control to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side at the end of an interaction initiated from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side, or to explicitly hand over control to the remote side.<BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot014.gif"></DIV><BR>
<BR>
<DT CLASS="dt-description"><B>rpc</B><DD CLASS="dd-description"> this message is sent before the remote side sends an ec_rpc goal
on the rpc connection. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot015.gif"></DIV><BR>
<BR>
After sending the <B>rpc</B> message, the remote side
should then send the ec_rpc goal (in EXDR format) on the rpc
connection. When the execution of the ec_rpc goal is finished, the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will yield control back to the remote side with a <B>yield</B> message, followed by the result of the ec_rpc execution on the rpc
connection (in EXDR format) &ndash; the goal with its bindings if the execution
succeeded; `fail' if the goal failed; `throw' if an exception is generated.<BR>
<BR>
<DT CLASS="dt-description"><B>rem_flushio(Queue)</B><DD CLASS="dd-description"> this message is sent if the remote side wish to
transfer data to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side on peer queue with queue id Queue, and
the remote side does not know how many bytes will be sent with the operation.<BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot016.gif"></DIV><BR>
<BR>
After sending the message, control is transferred over to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side, and the data is sent on the socket stream. On the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, if
the queue is a synchronous queue, then the data sent must be a single EXDR
term, because otherwise the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side would not know when the data
transfer is complete. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side would read the data from the
socket stream as a single EXDR term, which is then written onto the
buffer. If an event handler has been associated with the peer queue, this
will now be invoked to consume the data from the buffer. If not (for
example, if the <B>rem_flushio</B> was initiated by an <B>ec_waitio</B>
message), then the data is left on the buffer to be processed later.<BR>
<BR>
The <B>rem_flushio</B> message can also be used to sending data to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> for
asynchronous queues as well. In this case, an event handler is directly
associated with the socket stream, and this event is invoked when the
rem_flushio message is received. The event handler goal in this case is
invoked with the `culprit' argument being the term <TT>rem_flushio(Queue, Len)</TT>,
where Len is the atom `unknown'. It is up to the user-defined event handler
goal to properly read the data: since the length is unknown, the data sent
should have natural boundaries, e.g. EXDR terms, or use a mutually agreed
`end of data' marker.<BR>
<BR>
<DT CLASS="dt-description"><B>rem_flushio(Queue, Length)</B><DD CLASS="dd-description"> this message is sent if the remote side wish to
transfer data to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side on peer queue with queue id Queue, and
the length of data to be sent is known, and is specified in Length (the
number of bytes to be sent). <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot017.gif"></DIV><BR>
<BR>
After sending the message, control is transferred over to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side, and the data is sent on the socket stream. On the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, if
the queue is a synchronous queue, then it would read Length bytes of data
from the socket stream and transfer the data to the queue buffer.
If an event handler has been associated with the peer queue, this
will now be invoked to consume the data from the buffer. If not (for
example, if the <B>rem_flushio</B> was initiated by an <B>ec_waitio</B> message), then
the data is left on the buffer to be processed later.<BR>
<BR>
In the case that the peer queue is an asynchronous queue,
an event handler is directly
associated with the socket stream, and this event is invoked when the
rem_flushio message is received. The event handler goal in this case is
invoked with the `culprit' argument being the term <TT>rem_flushio(Queue, Length)</TT>,
It is up to the user-defined event handler goal to properly read the data.<BR>
<BR>
<DT CLASS="dt-description"><B>queue_create(Name, Type, Dir, Event)</B><DD CLASS="dd-description"> this message is sent when the
remote side wish to initiates the creation of a new peer queue. Name is the
name of the peer queue, Type is its Type: sync for synchronous, async for
asynchronous. Dir is the data direction: fromec or toec, and Event is the
name of the event that will be raised for the event handler goal on the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, if no event is to be associated with the queue, this
should be the empty atom (<CODE>''</CODE>).<BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot018.gif"></DIV><BR>
<BR>
Control is handed over to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, which should then set up a new
server socket for connecting the socket stream for the peer queue. Once
this server socket is set up, the creation of the queue proceeds via a
socket_client interaction from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, i.e. the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side
sends a <B>socket_client</B> message. For more detail, see the description
for the socket_client message. At the end of the socket_client interaction,
the peer queue would be established, and ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side has
control. The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will yield control back to the remote side,
completing the queue_create interaction.<BR>
<BR>
Note that the <B>socket_client</B> interaction is performed by the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> built-in <A HREF="../bips/kernel/externals/peer_queue_create-5.html"><B>peer_queue_create/5</B></A><A NAME="@default333"></A>, this is the goal that
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> calls on receiving the <B>queue_create</B> message.<BR>
<BR>
If the initial creation of the socket server fails, then the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side will not initiate a socket_client interaction. Instead, it will simple
yield control back to the remote side with a <B>yield</B> message. In this
case, no peer queue is created.<BR>
<BR>
<DT CLASS="dt-description"><B>queue_close(Queue)</B><DD CLASS="dd-description"> this message is sent when the remote side
closes the peer queue with id Queue. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot019.gif"></DIV><BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side should close the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side of the peer queue Queue, and
remove all bookkeeping information associated with it. Control should then
be returned to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> via a <B>yield</B> message. The queue should also be
closed on the remote side, with the bookkeeping information removed too.<BR>
<BR>
<DT CLASS="dt-description"><B>disconnect</B><DD CLASS="dd-description"> this message is sent if the remote side wish to initiate
disconnection. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot020.gif"></DIV><BR>
<BR>
Control is handed over to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, which will
acknowledge with <B>disconnect_yield</B> message. Once the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side
receives this message, the remote attachment between the two sides is
considered terminated. The remote side should now close all connections to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. Concurrently, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will also close down its
end of the connections.<BR>
<BR>
The <B>disconnect</B> message can be issued during an interaction. In such
cases, the interaction will be terminated early along with the attachment.<BR>
<BR>
<DT CLASS="dt-description"><B>disconnect_resume</B><DD CLASS="dd-description"> this message is sent in acknowledgement of a
disconnection initiated from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. <BR>
<BR>
<DIV CLASS="center">

<IMG SRC="embroot021.gif"></DIV><BR>
<BR>
After sending this
message, the remote attachment between the two sides is considered
terminated. The remote side should now close all connections to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. Concurrently, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will also close down its
end of the connections.
In addition, this message should be sent if the remote side has to
terminate the attachment while the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side has control. This can
happen if the remote process is forced to quit. This is the only case where
a message can be sent via the control connection on the remote side while
it does not have control. Once the message is sent, the remote side can
terminate its connection unilaterally. </DL>
<A NAME="toc61"></A>
<H3 CLASS="subsection"><A NAME="htoc114">10.5.1</A>&nbsp;&nbsp;The disconnection protocol</H3>
<A NAME="disconnect"></A>
Under normal circumstances, the disconnection of the two sides is initiated
by the side that has control, by sending a <B>disconnect</B> message to the
other side. The other side acknowledges this by responding with a <B>disconnect_yield</B> (ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side) or <B>disconnect_resume</B> (remote
side). The acknowledgement should be sent when that side is ready to
disconnect. Once the messages have been exchanged, both sides should be ready,
and can physically disconnect. The exchange of messages should ensure that
any asynchronous I/O between the two sides are properly terminated. <BR>
<BR>
However, under some circumstances, a side may be forced to disconnect when
it does not have control. For example, in the Tcl remote interface, the
root window for the Tcl process may be destroyed by the user. In such
cases, a unilateral disconnect will be performed by that side &ndash; only the
second part of the normal disconnect protocol is performed by sending the
disconnect acknowledge message (<B>disconnect_resume</B> or <B>disconnect_yield</B>) without being initiated by a <B>disconnect</B> message. <BR>
<BR>
The ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side checks the control connection for any unexpected
incoming messages before it sends an outgoing control message. If there is
a <B>disconnect_resume</B> message, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side will perform the
disconnection on its side. <BR>
<BR>
When the user exits normally from an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session, ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will
disconnect from all remote attachments. This is done in <B>sepia_end/0</B>
event handler.<BR>
<BR>
As part of the disconnection process on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, a user
definable event will be raised in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, just before the remote queues
are closed. This allows the user to define application specific handlers
for dealing with the disconnection of the remote interface (on the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side). A similar handler should
probably be provided on the remote side. The event raised has the same name
as the control stream. The event handler for this event is initially
defined to be <TT>true/0</TT> (i.e. a no-op) when the remote connection is set
up. The handler can then be redefined by the user, e.g. during the
user-defined initialisation during attachment:
<PRE CLASS="verbatim">

    ...
    remote_connect(localhost/MyPort, Control, 
        set_event_handler(Control, my_disconnect_handler/1)),
    ...

    my_disconnect_handler(Remote) :-  
    % just print out a message about the disconnection
        printf("Disconnected from remote attachment %w", [Remote]).

</PRE>
<HR>
<A HREF="embroot056.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot058.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
